Foundation for the docs overhaul tracked in CIP-3307:

- IA.md: living migration checklist at the repo root (one checkbox per
  planned page; sections tick off as they land on this branch)
- New `v2docs` collection (content/docs) served from the site root via a
  required catch-all route, alongside the legacy tree (content/stack)
  at /stack until every section migrates
- Frontmatter facet model: Diátaxis `type`, `components`, `audience`,
  `integration` (category / setup / pairsWith), and review-tracking
  fields (`verifiedAgainst`, `reviewBy`)
- Section scaffold: get-started, integrations (incl. the
  /integrations/supabase stub the Supabase listing links to), concepts,
  compare, guides, security, solutions, reference — meta.json + stubs
- v2-redirects.mjs: full legacy→v2 map (85/85 pages covered), gated
  behind ENABLE_V2_REDIRECTS=1 so the preview serves both trees during
  migration; /quickstart vanity redirect ships ungated
- scripts/validate-v2-redirects.ts wired into prebuild: CI fails if a
  legacy page has no v2 mapping
- llms.txt, llms-full.txt, sitemap, and the .mdx raw-markdown mirror
  now cover both trees

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

…t bare root

Two fixes from preview review:
- The bare domain root (Vercel preview URLs) 404'd because the app lives
  under the /docs basePath — added a basePath:false redirect / → /docs.
  In production only /docs/* reaches this app, so previews-only.
- The /docs landing was a standalone (home) page disconnected from the
  v2 nav, with every link pointing at legacy /stack URLs. It's now
  content/docs/index.mdx rendered inside DocsLayout (sidebar + search),
  linking the v2 sections. The catch-all became optional ([[...slug]])
  and the (home) route group is deleted (recoverable from history;
  CIP-3327 refines the landing content).
- The landing's raw-markdown mirror serves at /docs/index.mdx (its URL
  is "/", which can't carry the .mdx suffix).

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Listing "index" explicitly in meta.json pages forced each section's
index out as a separate child item with the same title as its folder
(clicking "Get started" opened a sub-nav containing another
"Get started"). With index unlisted, Fumadocs merges it into the folder
row: the folder itself links to the page, and children are only real
sub-pages (Integrations → Supabase, not Integrations → Integrations).
The root meta.json keeps "index" — at tree root there is no folder row
to merge into, so the landing needs its own sidebar item.

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Folders whose only page is their index still rendered as collapsible
sidebar folders with a chevron pointing at nothing. getV2PageTree()
now collapses such folders into plain page items (recursively, so
guides/* and reference/* leaves flatten too); a section becomes a
folder again automatically when its first real sub-page lands.

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

MDX links (markdown and Card hrefs) render through the Link component,
which prefixes the /docs basePath — hardcoded /docs/... links rendered
as /docs/docs/... and 404'd. Convention (enforce via CIP-3349 lint):
internal links in content are always basePath-relative.

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Seven pages replacing the v2-era EQL reference, written against the
eql_v3 branch of cipherstash/encrypt-query-language (3.0.0):

- index: what EQL is, the v3 domain-variant model, install (single SQL
  script, idempotent), dbdev, Docker, migration/runtime permission
  split, managed-Postgres rationale
- types: 10 scalar families × variants matrix; bool storage-only;
  _ord/_ord_ore twins; index terms per variant
- operators: per-variant support matrix, typed-operand rule, no-LIKE,
  fail-loud blockers, query shapes, function-form equivalents
- indexes: functional indexes on term extractors, engagement
  requirements, sort-key form for index-streamed ORDER BY, EXPLAIN
  checklist, large-table build guidance
- json: ste_vec model, per-node-type terms (hm XOR oc), containment +
  GIN, field access, path queries, blocked native jsonb operators
- functions: comparisons, extractors, min/max only (no SUM/AVG),
  version()
- payload-format: v/i/c envelope (wire version still v:2), hm/ob/bf
  term keys, sv document shape, annotated examples (absorbs the legacy
  CipherCell page)

Cross-page consistency verified against the shipped SQL: equality on
_ord variants compares ORE terms (no hm in _ord payloads), and bare
ORDER BY is correct but extractor-form sort keys stream from the index.

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

EQL is an abstraction over SQL the way Tailwind is over CSS — the docs
now follow the same shape: Install → Core concepts → type categories →
Indexes → query patterns, increasing in complexity. Each type-category
page is the complete reference for its types (variants, payload shape,
operators/functions, example queries on one page).

- index: trimmed to the Install page
- core-concepts (new): the canonical home for shared mechanics —
  variant model, payload anatomy (v/i/c envelope + hm/ob/bf terms,
  absorbs payload-format/CipherCell), typed-operand rule, fail-loud
  blockers, ORE-equality on _ord, term-leakage pointer
- numbers-and-dates, text, booleans (new) + json (reworked): category
  pages; text owns the no-LIKE treatment; json absorbs the sv payload
  shape; booleans framed as "every type has a storage-only variant —
  for bool it's the only one"
- filtering, sorting, grouping-and-aggregates, joins (new): cross-type
  query patterns; joins headlines the same-keyset constraint
- deleted: types.mdx, operators.mdx, functions.mdx, payload-format.mdx
  (content redistributed; URLs never shipped publicly, no redirect debt)
- Anti-drift rule recorded in IA.md: mechanics live ONLY in
  core-concepts; category/query pages link, never restate
- meta.json: flat URLs with ---Types---/---Indexes---/---Queries---
  sidebar separators; legacy redirect map retargeted (queries →
  filtering, cipher-cell → core-concepts)

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Docs V2: EQL v3 reference section, Tailwind-shaped (CIP-3326)

docs: add an EQL pin resolver so patch bumps stop relying on memory

…aying `any`

The generated Stack API reference documents 13 types as `any` and gives
AuthStrategy the wrong description entirely. Both come from one missing
compiler option.

@cipherstash/protect-ffi's `exports` map routes the `node` condition to
lib/index.d.cts (the real type surface) and everything else to
`default: ./dist/wasm/protect_ffi.js`, which ships no `types`. TypeScript
therefore falls through to the sibling dist/wasm/protect_ffi.d.ts — raw
wasm-bindgen output — where none of the hand-written types exist.

`moduleResolution: "bundler"` does not imply the `node` condition;
packages/stack/tsconfig.json adds `customConditions: ["node"]`, which is why
the stack team never sees this. But typedoc.tsconfig.json extends stack's ROOT
tsconfig, which does not set it. Set it on the generated config.

Confirmed with a minimal repro against protect-ffi 0.30.0 (the version stack
1.0.0-rc.4 pins exactly): `moduleResolution: bundler` alone yields
"has no exported member 'ProtectError'. Did you mean 'encryptQuery'?"; adding
customConditions typechecks clean.

Also turns error checking back on. It was disabled to tolerate this, on the
theory that the references were "unresolved even though the source is correct"
and TypeDoc would still emit accurate signatures. It does not — an unresolved
import becomes `any` in the output, so the workaround converted a loud failure
into a silently wrong reference. With the condition fixed the surface
typechecks with 0 errors, so the next resolution break fails the build instead.

Generating with and without the fix, back to back against the same stack tag,
changes 23 pages. Representative:

  EncryptionError.code            any -> ProtectErrorCode
  EncryptQueryOperation.execute() Promise<Result<any, ...>>
                                    -> Promise<Result<EncryptedQueryResult, ...>>
  encryptQuery plaintext param    any -> Plaintext | null | undefined
  AuthStrategy description        the module's blurb -> the type's own docs

Claude-Session: https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8

docs: resolve protect-ffi's real types so the Stack reference stops saying `any`

docs: EQL 3.0.4 — grouped_value, @@ fuzzy match, and the encrypted-JSON surface

chore: merge main into v2 (unblocks #37)

… API gate

Three changes, all about the docs telling the truth about the SDK.

1. Add @cipherstash/stack-supabase to the TypeDoc entry points.

Stack 1.0 split the Supabase adapter into its own package, and the entry points
were never updated, so NOTHING in it reached the generated reference —
encryptedSupabaseV3, the query builder, and the EQL-version constraints on its
encrypted operators were all absent. 19 pages now generate (763 total, up from
706), including the constraint that free-text and JSON operators are
"unavailable with EQL 3.0.2+" because PostgREST cannot express the required
eql_v3.query_* cast. That is now published automatically instead of relying on
someone reading the source.

2. Resolve a workspace package's subpath imports to source.

stack-supabase imports its sibling by package name (@cipherstash/stack,
/schema, /adapter-kit, ...), which resolves through that package's exports map
to ./dist — and the clone is never built, so all 42 imports were TS2307 and
every cross-package type would have documented as `any`. Derive the tsconfig
`paths` from the sibling's own exports map, rewriting ./dist/x.js to
./packages/<pkg>/src/x.ts, rather than hardcoding twelve subpaths that would
rot the next time Stack adds one. Two of them are not guessable
(`/types` -> types-public.ts, `/v3` -> encryption/v3.ts), which is the argument
for deriving rather than transcribing.

3. Say what the content API gate actually checks.

It printed "no deprecated or non-existent API found in documentation" while the
Supabase page taught `.contains()` for encrypted free-text, which raises. It is
a denylist of 7 patterns, not verification, so it now reports the rule count and
files scanned and states the limitation outright.

Deliberately NOT adding the version-diff denylist discussed: `contains()` was
repurposed rather than removed, so it is present in every tag and no
symbol-presence or signature diff fires on it. Catching that class needs the
examples typechecked against the SDK; the header now records that.

Also removes CLAUDE.md's "Required Skills" section. All six skills it mandated
(encryption, secrets, drizzle, supabase, dynamodb, update-docs) do not exist,
and its validation checklist was stale too — `switcher` appears in 0 files and
the "Good to know" callout in 1, versus <Callout> in 37. Its accurate items are
already covered by the Frontmatter, Code Blocks, and Formatting sections above.

Claude-Session: https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8

`validate-links` only ever looked at `content/stack`, and only at markdown
link syntax. That left the entire v2 tree unchecked, plus every
`<Card href=…>` in both trees — so a v2 page could be renamed or merged
away and every link to it would 404 against a green build. It also never
checked `#fragments` at all, in either tree.

It now walks both collections with their real base URLs (content/docs at
the root, content/stack under /stack), reads JSX href attributes as well
as markdown links, and resolves each `#fragment` against the target
page's headings.

Getting anchors right needed care:

- Headings are slugged with `github-slugger`, the same one Fumadocs uses,
  one instance per page so repeated headings get the same -1/-2 suffixes
  the renderer emits. Hand-rolled slugification is wrong in ways that
  matter here — "Sorting & range" is `sorting--range`, not
  `sorting-range`.
- Fumadocs' explicit `## Heading [#custom-id]` syntax is honoured.
- `<include cwd>` partials are inlined first, since their headings become
  anchors on the including page.
- Fenced code blocks are blanked (line numbers preserved), so a `#` in a
  bash sample isn't mistaken for a heading.

Non-page targets are resolved rather than skipped: static files under
public/ and static route handlers under src/app. Previously anything not
starting with /stack/ was waved through, which is precisely how the v2
tree escaped checking.

This surfaced 14 genuine breakages, all fixed here:

- 13 links to `searchable-encryption#exact-match`, `#match-pattern` and
  `#range--order` across 6 files. Those headings were renamed at some
  point to "Exact matching", "Free-text search" and "Sorting and range
  queries"; the links have been landing at the top of the page ever
  since, silently.
- `reference/drizzle.mdx` pointed at `/integrations/drizzle`, which does
  not exist on v2 yet — it arrives with #39. Dropped the forward
  reference; the API list under it already covers the surface.

TypeDoc output is gitignored and produced by `generate-docs`, so run
standalone on a fresh checkout every link into it looks broken. The
script now says so instead of emitting a wall of spurious errors —
`prebuild` generates before validating, which is why CI never sees it.

Claude-Session: https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8

Fumadocs ships the inverse of what we want: prose body text is
`--color-fd-foreground` at 90%, while DocsDescription — the standfirst
directly under the H1 — renders `text-fd-muted-foreground`. So the lead
line was the quietest text on the page and the body the loudest.

Swaps the two:

- `.prose` sets `--tw-prose-body` to `--color-fd-muted-foreground`. Only
  that one variable moves; headings, links, bold, code, quotes and
  captions each have their own, so they keep full contrast and now read
  as more distinct against the softer paragraph text.
- Both page routes pass `text-fd-foreground` to DocsDescription.

Both sides reference theme tokens, so light and dark follow the same rule
with no per-mode override.

The `.prose` rule is deliberately **unlayered**. Fumadocs declares
`.prose` in `@layer utilities`, and layer order beats both specificity and
source order — the same declaration inside the `@layer components` block
further down this file compiles fine and is silently ignored. Verified
against the built CSS rather than assumed: the shipped rule lands
unlayered, after fumadocs' own, and unlayered declarations outrank every
layer without needing `!important`.

Also verified in the built HTML that tailwind-merge resolves the class
conflict rather than emitting both — the description renders as
`text-lg mb-0 text-fd-foreground`, with the default muted class dropped.

Claude-Session: https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8

Two changes to Callout, plus a correction.

**The correction.** I claimed in #82's description that muting `.prose`
body text also muted callouts. That was wrong: Fumadocs hard-codes
`text-fd-muted-foreground` on `CalloutDescription`, set directly on that
div, so it overrides any inherited prose colour — and only `.prose`
itself consumes `--tw-prose-body`. Callout text has always been muted;
the body change did not touch it. The fix is the same either way, but
the reasoning in that description was not.

**Body text** now uses `text-fd-foreground`, matching the title (the
container is `text-fd-card-foreground`, which resolves to the same value
in both themes). A callout reads as one block instead of a heading over
greyed-out copy, and stands out from the surrounding muted body copy,
which is the point of a callout.

**Padding** doubles, `p-3 ps-1` → `p-6 ps-2`. `ps` stays proportionally
small because the accent bar is the container's first child and sits
near the edge.

Both need reaching the description, which Fumadocs' `Callout` does not
expose, so we compose `CalloutContainer` / `CalloutTitle` /
`CalloutDescription` — its exported primitives — instead. The container
still resolves the `warn`/`tip` aliases and picks the icon, so only the
trivial wrapper is reimplemented.

The wrapper also emits `data-callout`, which Fumadocs does not. global.css
has had a `[data-callout]` rule since the theme work that consequently
matched nothing; it now applies (its `border-radius: 2px` was already
coming from the `[class*="rounded-xl"]` rule above it, so nothing moves).

Verified in the built HTML rather than assumed — tailwind-merge collapses
both conflicts, leaving `p-6 ps-2` on the container and
`prose-no-margin empty:hidden text-fd-foreground` on the description, with
no muted class left anywhere in the callout subtree.

Claude-Session: https://claude.ai/code/session_01NkuQNMvw9BpB4BWWeKtfV8